<!DOCTYPE html>
<!--
  ~ Copyright (c) 2014, Francis Galiegue (fgaliegue@gmail.com)
  ~
  ~ This software is dual-licensed under:
  ~
  ~ - the Lesser General Public License (LGPL) version 3.0 or, at your option, any
  ~   later version;
  ~ - the Apache Software License (ASL) version 2.0.
  ~
  ~ The text of this file and of both licenses is available at the root of this
  ~ project or, if you have the jar distribution, in directory META-INF/, under
  ~ the names LGPL-3.0.txt and ASL-2.0.txt respectively.
  ~
  ~ Direct link to the sources:
  ~
  ~ - LGPL 3.0: https://www.gnu.org/licenses/lgpl-3.0.txt
  ~ - ASL 2.0: http://www.apache.org/licenses/LICENSE-2.0.txt
  -->

<html>
<head>
    <title>URI templates: generate URIs for your REST APIs</title>
</head>
<body>

<h2>Why URI templates</h2>

<p>The more time goes, the more you hear about so-called "REST APIs"; and these
REST APIs, ultimately, are nothing but URIs (or URLs if you prefer) with a
meaning.</p>

<p>Even before REST became all the craze, it was not uncommon, for instance, to
have personal pages accessible via <span
style="font-family: monospace;">http://the.site/~theuser</span> or the like.</p>

<p><a href="http://tools.ietf.org/html/rfc6570">URI Template</a> is an RFC which
defines a templating language for implementations to use to replace placeholders
with correctly encoded values. For instance, were you to make the URI above
parameterizable according to the username, you could write a template as:</p>

<pre>
    http://the.site/~{username}
</pre>

<p>A URI template engine (such as this one) would then be able, given a valid
definition for the <span style="font-family: monospace;">username</span>
variable, to transform this template into a URI -- even if your username were to
have accentuated characters.</p>

<h2>Why {@link java.net.URLEncoder}'s <span
    style="font-family: monospace">.encode()</span> doesn't work</h2>

<p>It does not work because its intent is not to encode strings for use in URIs
<span style="font-weight: bold">but in POST data</span> (ie, <span
style="font-family: monospace">aplication/x-www-form-urlencoded</span>)!</p>

<p>Encoding for this type of data is not the same as it is for URIs; the most
obvious example of it is the space, which this method encodes as a <span
style="font-family: monospace">+</span> whereas this character is illegal in a
URI (except in the fragment part).</p>

<h2>Sample usage</h2>

<p>Please see the <a href="https://github.com/fge/uri-template">project page</a>
for sample API usage.</p>

</body>
</html>